xv lets you do a large number of things (many of them actually useful), including, but not limited to, the following:
Unfortunately the Automatic Checkbook Balancing Module still isn't completely debugged, and is not included in this distribution.
Note: unless explicitly stated otherwise, the term click means "click with the Left mouse button."
Start the program up by typing 'xv'. After a short delay, a window will appear with the default image (the xv logo, credits and revision date) displayed in it. If you change the size of the window (using whatever method your window manager provides), the image will be automatically stretched to fit the window.
Clicking (and optionally dragging) the Left mouse button inside this window will display pixel information in the following format:
The first pair of numbers (196,137) are the x and y positions of the cursor, in image coordinates. These numbers remain the same regardless of any image resizing, or cropping. For example, if you click on the eye of the fish on the right side of the default image, you'll get (approximately) 251,129 regardless of the size of the displayed image. This allows you to zoom in for precise measurements.
The first triplet of numbers (191,121,209) are the RGB values of the selected pixel. The components will have integer values in the range 0-255. The values displayed are prior to any HSV/RGB modification, but after any colormap changes. See "Section 5: The Color Editor" for details.
The second triplet of numbers (287 42 81) are the HSV values of the selected pixel. The first component will have integer values in the range 0-359, and the second and third components will have integer values in the range 0-100. The values displayed are prior to any HSV/RGB modification, but after any colormap changes. See "Section 5: The Color Editor" for details. Also, see "Appendix D: RGB and HSV Colorspaces" for more information about what these numbers mean.
Note: If you actually want to measure some pixels, it will probably help to crop to a small region of your image, and expand that region to the point where you can see the individual pixels.
This string is automatically copied to your X server's cut buffer whenever you measure pixel values. This lets you easily feed this information to another program, useful if you're doing manual feature extraction, or something. Try it: measure a pixel's value, and then go click your Middle mouse button in an xterm window.
Bring up the xv controls window by typing the '?' key or clicking the Right mouse button inside the image window.
Clicking and dragging the Middle button of the mouse inside the image window will allow you to draw a cropping rectangle on the image. If you're unhappy with the one you've drawn, simply click the Middle button and draw another. If you'd like the rectangle to go away altogether, click the Middle button and release it without moving the mouse.
You can determine how large the cropping rectangle is (in image coordinates) by bringing up the xv info window. Do this by clicking the Info button in the xv controls window or by typing the 'i' key into any open xv window.
The xv info window will display, among other things, the current size and position of the cropping rectangle in terms of image coordinates. For example, if it says:
that would mean that the current cropping rectangle is 114 image pixels wide, 77 image pixels high, and its top-left corner is located 119 image pixels in from the left edge of the image, and 58 image pixels in from the top edge. These values will be updated as you drag the cropping rectangle around.
If you want to set the size or position of the cropping rectangle precisely, you can use the arrow keys on your keyboard. First, make the xv info window visible as described above (if it's not already visible). Second, use the mouse to draw a rough approximation of the cropping rectangle that you want. You can now use the arrow keys to move the cropping rectangle around the image. Once you've gotten the top and left sides of the cropping rectangle precisely where you want them, you can move the bottom-right corner of the cropping rectangle (only) by holding the <shift> key down while using the arrow keys. Pressing the up arrow will make the rectangle shorter, and pressing the down arrow will make the rectangle taller.
Once you have a cropping rectangle that you can live with, you can proceed with the actual cropping operation. Click the Crop button in the xv controls window, or type the 'c' key in any open xv window. The image window will shrink to show only portions of the image that were inside the cropping rectangle.
Note: if you are running a window manager such as mwm, which decorates windows with a title bar, resizing regions, and such, it is quite possible that the aspect ratio of the cropped image will get screwed up. This is because certain window managers enforce a minimum window size. If you try to crop to a rectangle that is too small, the window manager will create the smallest window it can, and the image will be stretched to fit this window. If this happens, you can press the Aspect button in the xv controls window, or type the 'a' key in any open xv window. This will expand the image so that it has the correct aspect ratio again.
You can crop a cropped image by repeating the same steps (drawing a new cropping rectangle and issuing the Crop command), ad infinitum.
You can return to the original, uncropped image by using the UnCrop command. Simply click the UnCrop button or type the 'u' key in any open xv window.
Note that if you try to make the cropping rectangle too small in either width or height (under 5 screen pixels), it'll just turn itself off. If you want to crop a very small portion of an image, you'll probably have to do it in two passes. First, crop to a small (but large enough to still be enabled) rectangle, expand that region, then crop again.
The xv controls window is the central point of control for the
program, hence the name. It provides controls to resize the current
image, flip and rotate it, load and save different files, and bring
up the other xv windows. It can be brought up by clicking the
Right mouse
button in the image window, or by typing the '?' key inside any
open xv window. Doing either of these things while the xv controls
window is visible will hide it.
All of the following commands may be executed by either clicking the appropriate command button, or typing the keyboard equivalent (where given) into any open xv window.
Note that none of the 'resizing' commands modify the image in any way. They only affect how the image is displayed. The image remains at its original size. This allows you to arbitrarily stretch and compact the image without compounding error caused by earlier resizing. In each case, the displayed image is recomputed from the original internal image.
This command may fail in two cases. If you're running a window manager (such as mwm) that enforces a minimum window size, and the 'normal' size is too small, the image may get distorted. See the note in "Section 2.2: Cropping" for more information.
Also, if the image is larger than the size of your screen, it will be 'halved' until it fits on the screen. For example, if you try to display a 1400x900 image on a 1280x1024 screen, the Normal command will display a 700x450 image.
Note that the window size is maintained as a pair of integers. As a result you may see some integer round-off problems. For example, if you halve a 265x185 image, you'll get a 132x92 image, which is just fine. However, if you Dbl Size this image, you'll get a 264x184 image, not the 265x185 image you might have expected.
It should be noted that the +10% and -10% commands have no concept of an 'original size'. They simply increase or decrease the current image size by 10%. As a result, they do not undo each other. For example, take a 320x200 image. Do a +10% and the image will be 352x220. If you issue the -10% command now, the image will be made (352 - 35.2)x(220 - 22), or 316x198.
Normally Aspect expands one axis of the image to correct the aspect ratio. If this would result in an image that is larger than the screen, the Aspect command will instead shrink one of the axes to correct the aspect ratio.
In addition to displaying an image in a window, xv can also display images on the root (background) window of your X display. There are a variety of ways that xv can display an image on the root window. The Display Modes popup menu lets you select where (and how) xv will display the image.
Click on the Display Modes button in the xv controls window, and hold the mouse button down. This will cause the Display Modes menu to pop up. The current display mode will be shown with a check mark next to it. To select a new mode, drag the mouse down to the desired mode, and release the mouse button.
It is not possible for xv to receive button presses or keyboard presses in the root window. As such, there are several functions that cannot be used while in a 'root' mode, such as pixel tracking and image cropping. If you want to do such things, you'll have to temporarily return to 'window' mode, and return to 'root' mode when you're finished. Also, when you are in a 'root' mode, you will not be able to get rid of the xv controls window. At best you can iconify it (using your window manager). (The reason for this is that if you ever got rid of it there'd be no way to get it back.)
Note: The three 'centered' modes (Root: Centered, Root: Centered, Warp, and Root: Centered, Brick, but not Root: Center Tiled) require the creation of a Pixmap the size of the screen. This can be a fairly large request for resources, and will fail on a color X terminal with insufficient memory. They can also require the transmission of considerably more data than the other 'root' modes. If you're on a brain-damaged X terminal hanging off a slow network, you should probably go somewhere else. Barring that, you should certainly avoid the 'centered' modes.
Also note: If you quit xv while displaying an image on the root window, the image will remain in the root window, and the colors used by the image will remain allocated. This is generally regarded as correct behavior. If you decide you want to get rid of the root image to free up resources, or simply because you're sick of seeing it, the quickest route is to use run 'xv -clear', which will clear the root window, release any allocated colors, and exit. Alternately, xsetroot and any other X program that puts things in the root window should be able to do the trick as well.
xv provides a a set of controls that let you conveniently operate on a list of images. To use the following commands, you'll have to start up xv with a list of filenames. For example, you could type 'xv *.gif' (assuming, of course, that you have a bunch of files that end with the suffix '.gif' in the current directory).
The filenames are listed in a scrollable window. The current selection is shown in reverse video. If there are more names than will fit in the window, the scrollbar will be enabled.
The scrollbar operates as follows:
If you click on a name in the list, that name will become highlighted. You can drag the highlight bar up and down, and the list will scroll appropriately.
It is also possible to control the list window from the keyboard. In all cases, you must make sure that the window sees the keypress. Generally, this means you have to have the cursor inside the window, though your window manager may also require you to click inside the window first.
You can directly view any image in the list by double-clicking on its filename. If xv is unable to load the file (for any of a variety of reasons), it'll display an error message and put up the default image, the xv logo.
The Delete command will pop-up a window asking you what you want to delete. Your choices are:
xv provides a window to display information about the current image, color allocation, expansion, cropping, and any error messages. This window can be opened by issuing the Info command. (Click on the Info button in the xv controls window, or type 'i' in any open xv window.) You can close the window by using the Info command while the window is open. You can also close the window by clicking anywhere inside it.
The top portion of the window displays the program name, revision date, and patchlevel. It also shows the University of Pennsylvania shield, the GRASP Lab logo, the copyright notice, and of course, the author's name.
The "Filename" field displays the name of the currently loaded file. The name is displayed without any leading pathname. If there is no currently loaded image (you're looking at the default image) this field will display "<none>".
The "Format" field displays information describing what image format the file is stored in, and how large the file is (in bytes).
The "Resolution" field shows the width and height (in image pixels) of the loaded image. Note that this does not necessarily have anything to do with the size of the image currently displayed on your screen. These numbers do not change as you modify the display image.
The "Cropping" field displays the current state of any cropping activity. If you are looking at the entire (uncropped) image, and there is no cropping rectangle drawn, this field will show "<none>". If you draw a cropping rectangle, or if you are viewing cropped portion of image, this field will display something like "247x128 rectangle starting at 132,421". See "Section 2.2: Cropping" for more details.
The "Expansion" field gives you information about how the image is displayed. It will display something like "1.58 x 1.37 (505 x 273)". This tells you that the current displayed image is 505 pixels wide and 273 pixels high, and that it is 1.58 times wider and 1.37 times higher than the internal image (which, in this case, had a size of 320x200).
The "Colors" field gives you detailed information on how well (or poorly) color allocation went. If everything went reasonably well it will display something like:
This means that 67 entries in the image's colormap were used in the image, but that only 66 of these colors were different, as far as the X server was concerned.
See "Appendix E: Color Allocation" for a complete discussion of how colors are allocated, and what the "Colors" field can tell you.
Note that the fields are filled in as information becomes available. As such, they can be used as a rough 'progress indicator' when loading images. When you begin loading, all the fields are cleared. Once the image has been successfully loaded, the top three fields (Filename, Format, Resolution) are filled in. Once the colors have been allocated, and the display image generated, the bottom three fields are shown (Cropping, Expansion, and Colors).
The bottom two lines in the info window display various error messages, warnings, and status information. These two lines are also duplicated in the xv controls window.
The upper line is the more commonly used. It normally displays a one-line summary of the current image and color allocation success. If an error occurs, it will be displayed on this line as well.
The lower line is used to display warning messages.
The xv color editor provides a powerful system for manipulating color images. Since there are many different reasons why a person would want to modify an image's colors, and many different types of images that may need modification, there is no one color manipulation tool that would be 'best' for all purposes. Because of this problem, xv gives the user three different color tools, all of which can be used simultaneously.
The major use of the RGB Modification tool is to correct for the differing color response curves of various color monitors, printers, and scanners. This is the tool to use when "the image is too red", for instance.
These three tools are tied together in a fixed order. The Colormap Editing tool operates on the original colors in the image. The output of this tool is piped into the HSV Modification tool. Its output is piped into the RGB Modification tool. The output from the RGB Modification tool is what actually gets displayed.
In addition there is a collection of buttons that control the xv color editor as a whole (more or less).
Don't Panic! It's not as complicated as it looks.
The top portion of this window shows the colormap of the current image. There are 16 cells across, and up to 16 rows down, for a maximum of 256 color cells. Only cells actually used somewhere in the image are shown in this array.
The currently selected color cell is shown with a thick border. You can change the selection by clicking anywhere in the array. If you drag the mouse through this area, you'll see the dials at the bottom change to track the current pixel values.
You can also select a color cell by clicking anywhere in the image window. Whichever pixel value you were on when you let go of the mouse will become the new selected color cell.
Since certain images will have many colors that are the same, or nearly the same, it is sometimes convenient to group color cells together. Grouped color cells all take on the same color, and changing any one of them affects all of the other colors in the group.
To group color cells together, do the following:
You can create as many groups as you like.
You can use this grouping/ungrouping technique to copy colors from one color cell to another. Left click on the source color cell, Right click on the destination color cell, and Right click on the destination color cell again (to ungroup it).
At the bottom the Colormap Editing tool are three dials that let you set the color of the current color cell (or group of cells). By default, the dials control the Red, Green, and Blue components of the RGB colorspace, but they can also control the Hue, Saturation, and Value components of the HSV colorspace. (The RGB/HSV button controls this.)
Regardless of what they control, all dials in xv work the same way. Clicking on the single arrows increase/decrease the value by 1. Clicking on the double arrows increase/decrease the value by a larger amount (16 in this case). If you click on one of the arrows, and hold the mouse button down, the increase/decrease will repeat until you release the mouse button.
You can also click in the general area of the pointer and simply drag it to the position you want. The further your mouse cursor is from the center of the dial, the more precise the control will be. While dragging, you do not have to keep the cursor inside the dial window.
In RGB mode, each color component is separately 'inverted'. For example, Yellow (which is composed of full red, full green, and no blue) would turn to Blue (no red, no green, full blue).
In HSV mode, only the Value (intensity) component is 'inverted'. The Hue and Saturation components remain the same. In this mode, bright colors turn to dark versions of the same color. For example, a Yellow would turn Brown.
Note: It is HIGHLY RECOMMENDED that if you're using the Colormap Editing tool, you do NOT use the HSV Modification tool or the RGB Modification tool as well. If you do, the results can be quite confusing. For example, you might edit a color cell, and set its color values to produce a purple. However, because of HSV/RGB Modification further down the line, the actual color displayed on the image (and in the color cell) is yellow. Very confusing, indeed.
There are four separate controls in the HSV Modification tool. At the top of the window are a pair of circular controls that handle hue remapping. Lower down is a circular control that maps 'white' (and greys) to a specified color. There is a dial control that lets you saturate/desaturate the colors of the current information. Finally, at the bottom there is a graph window that lets you modify intensity values via an arbitrary remapping function.
These two dials are used to define a source and a destination range of hue values. Every hue in the source range (defined in the From dial) gets mapped to the value of the corresponding point in the destination range (defined in the To dial).
Each dial has a pair of radial lines with handles at their ends. Between the two lines an arc is drawn with an arrow at one end. The wedge drawn by these lines and the arc defines a range of values (in degrees). The direction of the arc (clockwise, or counter-clockwise) determines the direction of this range of values (increasing or decreasing).
Distributed around the dial are tick marks and the letters 'R', 'Y', 'G', 'C', 'B', and 'M'. These letters stand for the colors Red, Yellow, Green, Cyan, Blue, and Magenta, and they show where these colors appear on the circle.
The range is shown numerically below the control. By default the range is '330, 30 CW'. This means that a range of values [330, 331, 332, ... 359, 0, 1, ... 28, 29, 30] has been defined. Note that (being a circle) it wraps back to 0 after 359.
The range can be changed in many different ways. You can click on the 'handles' at the end of the radial lines and move them around. If you click inside the dial, but not on one of the handles, you'll be able to drag the range around as a single object. There are also 5 buttons below the dial that let you rotate the range, flip the direction of the range, and increase/decrease the size of the range while keeping it centered around the same value.
In its default state, the To dial is set to the same range as the From dial. When the two dials are set to the same range, they are effectively 'turned off', and ignored.
An example of hue remapping:
Note that the values printed when you are tracking pixel values in the image are the values before the HSV Modification tool is applied. For example, the background of the default image will still claim to be blue, regardless of what color you may have changed it to. This is so that you know what Hue value you will need to remap if you want to change its color again.
If you press the Reset button that is located near the hue remapping controls, it will effectively disable the hue remapping by setting the To range equal to the From range.
Below the hue remapping controls are a group of 'radio buttons'. You can have up to six different hue remappings happening simultaneously. Higher numbered mappings take precedence over lower number mappings.
An example of multiple hue remappings:
Note that the six hue remappings are not 'cascaded'. The output of one remapping is not fed as input into any of the other hue remappings. The hue remappings always operate on the hue values in the original image. In this example, if remapping #1 adds 32 to all hue values, thereby mapping the blue background (value 240) into a purple-blue (value 272), remapping #2 still sees the background at 240, and can remap it to anything it likes. Similarly, in the same example, if remapping #1 has mapped a green-blue color (value 208) into blue (value 240), remapping #2 will not map this into another color. As far as remapping #2 is concerned, that green-blue is still green-blue.
If it seems complicated, I'm sorry. It is.
In the HSV colorspace, 'white' (including black, and all the greys in between) has no Hue or Saturation components. As such, it is not possible to use the hue remapping controls to change the color of white pixels in the image, since they have no 'color' to change.
The white remapping control provides a way to add Hue and Saturation components to all the whites in the image. It consists of a movable point in a color dial. The angle of the dot from the center of the dial determines the Hue component. The distance of the dot from the center of the dial determines the Saturation component. The further the dot is from the center of the dial, the more saturated the color will be.
You can control the white remapping control in several ways. You can click on the handle and drag it around with the mouse. There are also four buttons provided under the dial. One pair allows you to rotate the handle clockwise and counter-clockwise without changing its distance from the center. The other pair of buttons lets you change the distance between the handle and the center without changing the angle.
The current Hue and Saturation values provided by the control is displayed below the dial. The first number is the Hue component, in degrees, and the second is the Saturation component, as a percentage.
There is also a checkbox that will let you turn off the white remapping control. This lets you quickly compare your modified 'white' with the original white. You can also effectively disable the white remapping control by putting the handle back in the center of the control. The easiest way to do this is to click and hold the 'move towards center' button until the saturation gets down to 0%.
Example:
The saturation control lets you globally increase or decrease the color saturation of the image. In effect, it is much like the 'color' control on most color televisions.
The saturation control is a dial that operates exactly like the dials described in "Section 5.2.1 Using the Dial Controls". In short, you can click and hold down any of the four buttons in the bottom of the control to increase or decrease the control's value. You can also click on the dial itself and move the pointer around directly.
The saturation control has values that range from '-100%' to '+100%'. At its default setting of '0%', the saturation control has no effect on the image. As the values increase, the colors become more saturated, up to '+100%' where every color is fully saturated. Likewise, as values decrease, the colors become desaturated. At '-100%', every color will become a completely desaturated (i.e., a shade of grey). Note that this control is applied after the the White Remapping control, so if you 'greyify' the image by completely desaturating it, you will not be able to color it using the White Remapping control.
Unless you're trying for some special effects, the useful range of this control is probably '+/-20%'. Also note that the control will have no effect on shades of grey, as they have no color to saturate.
The intensity graph allows you to change the brightness of the image, change the contrast of the image, and get some unique effects.
The intensity graph is a function that lets you remap intensity values (the Value component in HSV Colorspace) into other intensity values. The input and output values of this function both range from 0 to 255. The input values range along the x axis of this graph (the horizontal). For every input value (point along the x axis) there is a unique output value determined by the height of the graph at that point. In the graph's default state, the function is a straight line from bottom-left to top-right. In this case, each input value produces an equivalent output value, and the graph has no effect.
There are a number of 'handles' along the graph. These provide your major means of interacting with the graph. You can move them around arbitrarily, subject to these two constraints: the handles at the far left and far right of the graph can only be moved vertically, and handles must remain between their neighboring handles for the graph to remain a proper function.
The handles are normally connected by a spline curve. To see this, move one of the handles by clicking and dragging it. The function will remain a smoothly curved line that passes through all the handles. You can change this behavior by putting the function into 'lines' mode. Press the 'lines' button (the second button down from the top). The function will change to a series of line segments that connect the handles. Press the 'spline' button (the top button) to go back to 'spline' mode.
The next two buttons let you add or delete handles. The 'add handle' button will insert a handle into the largest 'gap' in the function. The 'delete handle' button will remove a handle from the smallest 'gap' in the function. You can have as little as 2 handles, or as many as 16. Note that as the number of handles gets large, the spline will start getting out of control. You may wish to switch to 'lines' mode in this case.
The 'Reset' button puts everything back on a straight line connecting bottom-left to top-right (a 1:1 function). It does not change the number of handles, nor does it change the x-positions of the handles.
The 'Gam' button lets you set the function curve by entering a single number. The function is set equal to the gamma function:
where I is the input value (0-255), g is the gamma value, and Y is the computed result.
Gamma values (for our purposes) can range between 0 and 10000, non-inclusive.
There is a shortcut for the 'Gam' button. Type 'g' while the mouse is inside the graph window.
Also, touching any of the handles after a 'Gam' command will put the graph back into its 'normal' mode. (Either 'spline' or 'lines' depending on which of the top two buttons is turned on.)
Generally, whenever you move a graph handle and let go of it, the image will be redrawn to show you the effects of what you've done. This can be time-consuming if you intend to move many points around. You can temporarily prevent the redisplay of the image by holding down a <shift> key. Continue to hold the <shift> key down while you move the handles to the new position. Release the <shift> key when you're done, and the image will be redisplayed.
The RGB Modification tool is a collection of three graph windows, each of which operate on one of the components of the RGB colorspace. This tool lets you perform global color-correction on the image by boosting or cutting the values of one or more of the RGB color components. You can use this to correct for color screens that are 'too blue', or for color printers that produce 'brownish' output, or whatever.
The graphs work exactly as explained in "Section 5.3.4: The Intensity Graph".
Neat Trick: In addition to color-correction, you can use the RGB modification tool to add color to images that didn't have color to begin with. For instance, you can 'pseudo-color' a greyscale image.
An example of pseudo-coloring:
You now have a transformation that will take greyscale images and display them in pseudo-color, using a 'temperature' color scheme. Neato!
These buttons provide general control over the whole xv color editor window. You can display the image with or without color modification, save and recall presets, and undo/redo changes. Also, convenience controls are given for performing some of the most common operations on the Intensity graph.
This is only useful when the 'Auto-apply HSV/RGB mods' checkbox is off.
It may be helpful to think of xv as maintaining a series of 32 'snapshots' of the HSV and RGB controls. You are normally looking at the last frame in this series. The Undo control moves you backwards in the series.
The 'Display with HSV/RGB mods' checkbox tells you whether or you're looking at a modified image (checked) or the 'raw', unmodified image (unchecked). The Apply and NoMod buttons change the setting of this checkbox, and you can also change the checkbox directly by clicking on it.
The 'Auto-apply HSV/RGB mods' checkbox controls whether or not the program regenerates and redisplays the image after each change to an HSV or RGB control. By default, this checkbox is turned on, so that you can easily see the results of your modifications. However, in the case that you want to make a large number of changes at once, it might be preferable to turn automatic redisplay off for a while, to speed things up.
The 'Auto-reset on new image' checkbox controls whether or not the HSV and RGB controls are Reset back to their default values whenever a new image is loaded up. By default, this is also turned on, as when you're playing with the HSV/RGB controls, you probably only want to affect the current image, and not all subsequently loaded images as well.
The xv load window lets you load and view images interactively, without specifying them on the command line when you start xv.
The load window shows the contents of the current directory in a scrolling window. The files will be sorted alphabetically, with all the directories (and symbolic links to directories, if your operating system supports them) displayed first.
This list window operates in the same way that the one in the xv controls window works. (See "Section 3.6.1: Operating a List Window" for details.) In short, you can operate the scroll bar, drag the highlight bar around the window, and use the up-arrow, down-arrow, Home, End, Page Up, and Page Down keys on your keyboard.
Whenever you click on a name in the list (or otherwise change the position of the highlight bar), the name of the highlighted file is copied to the "Load file" text entry region, located below the list window. Pressing the Ok button (or typing <return>) will cause the program to attempt to load the specified file. If the load attempt is successful, the load window will disappear, and the new image will be displayed. Otherwise, an error message will be displayed, and the load window will remain visible.
If the image is successfully loaded, its name will be added to the xv controls window list. This will let you quickly reload it later without have to go through the xv load window again.
You can also load a file by double-clicking on its name in the file list.
If the specified file is a directory, xv will figure that out and (instead of loading it) will 'cd' to that directory, and display its contents in the list window.
Above the list window is a pop-up menu button, much like the Display Modes button in the xv controls window. It normally displays the name of the current directory. If you click this button, and hold the mouse down, the complete path will be shown, one directory per line. You can go 'up' the directory tree any number of levels, all the way up to the root directory, by simply selecting a directory name in this list.
For those who prefer the direct approach, you can simply type file or directory names in the "Load file" text entry region. If you type a directory name and hit <return>, xv will 'cd' to that directory and display its contents in the list window. If you type a file name and hit <return>, xv will attempt to load the file. You can enter relative paths (relative to the currently displayed directory), absolute paths, and even paths that begin with a '~'.
The "Load file" text entry region supports a number of emacs-like editing keys.
If the filename is so long that it cannot be completely displayed in the text entry region, a thick line will appear on the left or right side (or both sides) of the region to show that "there's more over this way".
The xv save window lets you write images back to disk, presumably after you've modified them. You can write images back many different formats, not just the original format.
For the most part, the xv save window operates exactly like the xv load window. (See "Section 6: The Load Window" for details.) Only the differences are listed here.
When the window is opened, it should have the filename of the currently loaded file already entered into the text entry region. If you change directories, or click on a file name in the list window, this name will be cleared and replaced with the new name.
At the bottom of the window are a list of possible formats in which you can save the file. If you click on one of these formats, and your filename has a recognized suffix (i.e., '.gif', '.GIF', '.pbm', etc.), the suffix portion of your filename will be replaced with the new, appropriate suffix for the selected format.
You can pipe output from xv to other programs by using the xv save window. A fine use for this feature is directly printing images to a PostScript printer by selecting 'PostScript' in the formats list, and typing something like "| lpr" as the filename. In this case, xv will create a temporary file, write the PostScript to that file, and cat the contents of that file to the entered command. XV will wait for the command to complete. If the command completed successfully, the xv save window will disappear. If the command was unsuccessful, the window will remain visible. In any event, the temporary file will be deleted.
At the bottom right side of the window there is a list of possible 'Color' variations to save. Most file formats support different 'sub-formats' for 24-bit color, 8-bit greyscale, 1-bit B/W stippled, etc. Not all of them do. Likewise, not all 'Color' choices are available in all formats.
In general, the 'Color' choices do the following:
Format notes:
Since GIF only supports one format (up to 8 bits per pixel, with a colormap), there will be no size difference between a Full Color and a Greyscale image. A B/W Dithered image, on the other hand, will be considerably smaller.
In the raw variation of the PBM formats, the header information is written in plain ASCII text, and the image data is written as binary data. This is the more popular of the two dialects of PBM.
Note that xv-produced PBM files may break some PBM readers that do not correctly parse comments. If your PBM reader cannot parse comments, you can easily edit the PBM file and remove the comment lines. A comment is everything from a "#" character to the end of the line.
XV writes Encapsulated PostScript, so you can incorporate xv-generated PostScript into many desktop-publishing programs. XV also prepends some color-to-greyscale code, so even if your printer doesn't support color, you can still print 'color' PostScript images. These images will be three times larger (in file size) than their greyscale counterparts, so it's a good idea to save Greyscale PostScript, unless you know you may be printing the file on a color printer at some point.
Also, you should probably never need to generate B/W Dithered PostScript, as every PostScript printer I've ever heard of can print greyscale images. The only valid cases I can think of are: A) doing it for a special effect, and B) doing it to generate a much smaller (roughly 1/8th the size) PostScript file.
Note: When you try to save a PostScript file, the xv postscript window will pop up to let you specify how you want the image printed. (See "Section 8: The PostScript Window", for details.)
When you save in the JPEG format, a dialog box will pop up and ask you for a quality setting. '75%' is the default value, and really, it's a fine value. You shouldn't have to change it unless you're specifically trying to trade off quality for compression, or vice versa. The useful range of values is 5%-95%.
The xv postscript window lets you describe how your image should look when printed. You can set the paper size and the image size, position the image on the paper, and print in 'portrait' or 'landscape' mode.
The majority of the xv postscript window is taken up by a window that shows a white rectangle (the page) with a black rectangle (the image) positioned on it. You can position the image rectangle anywhere on the page. The only constraint is that the center of the image (where the two diagonal lines meet) must remain on the page. Only the portion of the image that is on the page will actually be printed.
The image can be (roughly) positioned on the page by clicking in the image rectangle and dragging it around. As you move the image, the "Top" and "Left" position displays will show the size of the top and left margins (the distance between the top-left corner of the page and the top-left corner of the image).
You'll note that you have limited placement resolution with the mouse. If you want to fine-position the image, you can use the arrow keys to move the image around. The arrow keys will move the image in .001" increments. You can hold them down, and they will auto-repeat. You can also hold a <shift> key down while using the arrow keys. This will move the image in .01" increments.
You can change the size of the printed image by adjusting the "Width" or "Height" dials. Normally, the dials are locked together, to keep the aspect ratio of the image constant. You can unlock the dials by turning the off the checkbox located below the dials. As you change the dials, the size of the image (when printed) is displayed below, in inches and in millimeters. The current resolution of the image is also displayed below. The "Resolution" numbers tell you how many image pixels will be printed per inch.
Located below the 'page' rectangle are a set of radio buttons that let you specify the current paper size (8.5" x 11", 8.5" x 14", 11" x 17", A4, and B5), and orientation (Portrait and Landscape).
The Center button will center the image on the page. The Maxpect button will make the image as large as possible (maintaining half-inch margins on all sides) without changing the aspect ratio.
There are a pair of small buttons located next to the "Left" and "Top" displays. Clicking the "Left" one will cycle between displaying the "Left" margin, the "Right" margin, and the "Center X" position (the distance from the left edge of the paper to the center of the image).
Clicking the "Top" display's button will cycle between displaying the size of the "Top" margin, the size of the "Bottom" margin, and the "Center Y" position (the distance from the top edge of the paper to the center of the image).
Click the "Ok" button when you're finished with the xv postscript window. If everything is successful, the xv postscript and the xv save window will both close. If xv was unable to write the PostScript file, the xv postscript window will close, but the xv save window will remain open, to give you a chance to enter a different filename.
XV supports literally dozens of command line options and X11 resources. Fortunately, it is doubtful that you'll ever need to use more than a small few. The rest are provided mainly for that 'one special case' application of xv...
If you start xv with the command 'xv -help', the current list of options will be displayed:
For example, if you give a rectangular geometry of '320x240', and you try to display a square picture with a size of '256x256', the window opened will actually be '240x240', which is the largest square that still fits in the '320x240' rectangle that was specified.
Factors less than zero are treated as reciprocals. (i.e., an expand factor of '-4' makes the picture 1/4th its normal size.). '0' is not a valid expansion factor.
Aspect ratios greater than '1:1' (e.g., '4:3') make the picture wider than normal. Aspect ratios less than '1:1' (e.g. '2:3') make the picture taller than normal. (Useful aspect ratio: A 512x480 image that was supposed to fill a standard 4x3 video screen (produced by many video digitizers) should be displayed with an aspect ratio of '5:4')
It should be noted that 'use global colors' is the default because color changes aren't generally a problem if you are only using xv to display a picture for a short time. Color changes only really become a problem if you use xv to display a picture that you will be keeping around for a while, while you go and do some other work (such as using xv to display a background). In such cases you will want to specify -nglobal. Note: using the -ncols or -root options automatically turn on -nglobal.
The following options only come into play if you are using xv to display 24-bit RGB data (PPM files, color PM files, JPEG files, and the output of bggen). They have no effect whatsoever on how GIF pictures or 8-bit greyscale images are displayed.
Advantages: The -slow24 algorithm often produces better looking pictures.
Disadvantages: The -slow24 algorithm is about half the speed of the default algorithm. Also, since the colors are chosen on a per-image basis, it can't be used to display multiple images simultaneously, as each image will almost certainly want a different set of 256 colors. The default algorithm, however, uses the same exact colors for all images, so it can display many images simultaneously, without running out of colors. Also, the -slow24 algorithm occasionally produces worse-looking pictures than the default algorithm, particularly on displays with very few colors. The default algorithm produces nice, dependably 'okay' pictures.
Advantages: The pictures will be displayed 'perfectly', whereas if they went through either of the conversion algorithms, they'd be dithered.
Disadvantages: Often uses a lot of colors, which limits the ability to view multiple images at once. (See the -slow24 option above for further info about color sharing.)
xv has the ability to display images on the root window of an X display, rather than opening its own window (the default behavior). When using the root window, the program is somewhat limited, because the program cannot receive input events (key press and mouse clicks) from the root window. As a result, you cannot track pixel values, or crop, nor can you use keyboard commands while the mouse is in the root window.
XV currently consists of three main windows, plus one window for the actual image. These three windows (the xv controls window, the xv info window, and the xv color editor window) may be automatically mapped and positioned when the program starts.
Try something like: 'xv -ncols 0 -bl red -wh yellow <filename>' for some interesting, late-'60s-style psychodelia effects.
Just in case you're wondering why there's any size limitations: it's fairly easy to accidentally ask for a huge image to be generated. Simply crop a section of the image, zoom so you can see the individual pixels, and uncrop. If there were no size limitations, the (expanded many times) image could be huge, and might crash your X server. At the very least, it would take a long period of time, and freeze your X server during part of it. Generally undesirable behavior.
You can set default values for all of the HSV and RGB modification controls in the xv color editor window via X resources. The easiest way to explain this is with an example.
The lines generated by Cut Resources will look like the following:
xv.default.huemap1: 330 30 CW 330 30 CW
xv.default.huemap2: 30 90 CW 30 90 CW
xv.default.huemap3: 90 150 CW 90 150 CW
xv.default.huemap4: 150 210 CW 150 210 CW
xv.default.huemap5: 210 270 CW 210 270 CW
xv.default.huemap6: 270 330 CW 270 330 CW
xv.default.whtmap: 0 0 1
xv.default.satval: 0
xv.default.igraf: S 4 : 0,0 : 64,64 : 192,192 : 254,254
xv.default.rgraf: S 4 : 0,0 : 64,64 : 192,192 : 254,254
xv.default.ggraf: S 4 : 0,0 : 64,64 : 192,192 : 254,254
xv.default.bgraf: S 4 : 0,0 : 64,64 : 192,192 : 254,254
These lines completely describe one state of the xv color editor controls. There are five different states that you can specify via X resources. The 'default' state (as shown) holds the settings used whenever the program is first started, and whenever the Reset command is used. You can also store settings in one of the four xv presets (accessed via the '1'-'4' buttons in the xv color editor) by changing the string 'default' in the above lines to 'preset1', 'preset2', 'preset3', or 'preset4' respectively.
There are four types of resource described in these lines: huemap, whtmap, satval, and graf.
The huemap resources describe the state of the hue remapping dials. There are six huemap resources per state of the xv color editor. These huemap resources are numbered 'huemap1', 'huemap2', ... 'huemap6', and correspond to the '1'-'6' radio buttons under the hue remapping dials.
Each huemap resources takes six parameters:
The whtmap resource describes the state of the white remapping control. There is one whtmap resource per state of the xv color editor controls. The whtmap resource takes three parameters:
The satval resource describes the value of the Saturation dial. There is one satval resource per state. The satval resource takes a single integer value, in the range +/-100, which specifies how much to add or subtract to overall image color saturation.
The graf resources describe the state of the four 'graph' windows in the xv color editor window (Intensity, Red, Green, and Blue). The graf resources can be in one of two formats, 'gamma' and 'spline/line'.
In 'gamma' format, the graf resource takes two parameters:
In 'spline/line' mode, the graf resource takes a variable number of parameters:
It also only displays the first image in GIF files that have multiple images in them.
As for PM pictures, this program only displays 1-plane PM_I pictures, or 1-, 3-, or 4-plane PM_C pictures.
The 4-, 6-, 16-, 24-, and 32-bit code has not been extensively tested. (A 4-bit MicroVax GPX system, a 6-bit HP 9000/320, a 16-bit Sony 3710, and a 24-bit HP 9000/350, respectively. The 32-bit code hasn't actually been tested at all.) You won't be able to do '-ncols 0' on a 6-, 16-, 24-, or 32-bit display, not that you should want to.
GIF reading code based on gif2ras.c, by Patrick J. Naughton (naughton@wind.sun.com)
GIF writing code essentially unchanged from code written by Michael Maudlin (mlm@cs.cmu.edu).
SUN Rasterfile i/o code written by Dave Heath (heath@cs.jhu.edu)
JPEG interface code written by Markus Baur (s_baur@iravcl.ira.uka.de)
JPEG i/o code provided by the Independent JPEG Group.